﻿//---------------------------------------------------------------------
// <copyright file="ODataWriter.cs" company="Microsoft">
//      Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>
//---------------------------------------------------------------------

namespace Microsoft.Data.OData
{
    using System;
#if ODATALIB_ASYNC
    using System.Threading.Tasks; 
#endif

    /// <summary>
    /// Base class for OData writers.
    /// </summary>
    public abstract class ODataWriter
    {

        /// <summary>Starts the writing of a feed.</summary>
        /// <param name="feed">The feed or collection to write.</param>
        public abstract void WriteStart(ODataFeed feed);

        /// <summary>Starts the writing of an entry.</summary>
        /// <param name="entry">The entry or item to write.</param>
        public abstract void WriteStart(ODataEntry entry);

        /// <summary>Starts the writing of a navigation link.</summary>
        /// <param name="navigationLink">The navigation link to write.</param>
        public abstract void WriteStart(ODataNavigationLink navigationLink);

        /// <summary>Finishes the writing of a feed, an entry, or a navigation link.</summary>
        public abstract void WriteEnd();

        /// <summary> Writes an entity reference link, which is used to represent binding to an existing resource in a request payload. </summary>
        /// <param name="entityReferenceLink">The entity reference link to write.</param>
        /// <remarks>
        /// This method can only be called for writing request messages. The entity reference link must be surrounded
        /// by a navigation link written through WriteStart/WriteEnd.
        /// The <see cref="P:Microsoft.Data.OData.ODataNavigationLink.Url" /> will be ignored in that case and the Uri from the <see cref="P:Microsoft.Data.OData.ODataEntityReferenceLink.Url" /> will be used
        /// as the binding URL to be written.
        /// </remarks>
        public abstract void WriteEntityReferenceLink(ODataEntityReferenceLink entityReferenceLink);

        /// <summary>Flushes the write buffer to the underlying stream.</summary>
        public abstract void Flush();

#if ODATALIB_ASYNC
        /// <summary> Asynchronously start writing a feed. </summary>
        /// <returns>A task instance that represents the asynchronous write operation.</returns>
        /// <param name="feed">The feed or collection to write.</param>
        public abstract Task WriteStartAsync(ODataFeed feed); 

        /// <summary> Asynchronously start writing an entry. </summary>
        /// <returns>A task instance that represents the asynchronous write operation.</returns>
        /// <param name="entry">The entry or item to write.</param>
        public abstract Task WriteStartAsync(ODataEntry entry); 

        /// <summary> Asynchronously start writing a navigation link. </summary>
        /// <returns>A task instance that represents the asynchronous write operation.</returns>
        /// <param name="navigationLink">The navigation link to writer.</param>
        public abstract Task WriteStartAsync(ODataNavigationLink navigationLink); 

        /// <summary> Asynchronously finish writing a feed, entry, or navigation link. </summary>
        /// <returns>A task instance that represents the asynchronous write operation.</returns>
        public abstract Task WriteEndAsync(); 

        /// <summary> Asynchronously writes an entity reference link, which is used to represent binding to an existing resource in a request payload. </summary>
        /// <returns>A task instance that represents the asynchronous write operation.</returns>
        /// <param name="entityReferenceLink">The entity reference link to write.</param>
        /// <remarks>
        /// This method can only be called for writing request messages. The entity reference link must be surrounded
        /// by a navigation link written through WriteStart/WriteEnd.
        /// The <see cref="P:Microsoft.Data.OData.ODataNavigationLink.Url" /> will be ignored in that case and the Uri from the <see cref="P:Microsoft.Data.OData.ODataEntityReferenceLink.Url" /> will be used
        /// as the binding URL to be written.
        /// </remarks>
        public abstract Task WriteEntityReferenceLinkAsync(ODataEntityReferenceLink entityReferenceLink); 

        /// <summary>Flushes the write buffer to the underlying stream asynchronously.</summary>
        /// <returns>A task instance that represents the asynchronous operation.</returns>
        public abstract Task FlushAsync(); 
#endif
    }
}
